Comment API Design Decisions

The API design for a service not only depends on the organization's requirements and the services they provide, but it also depends on the internal details of the system's overall architecture. These decisions further pave the way to adopt a specific API architecture style to direct the communication between the clients and back-end services. In the following section, we'll discuss the detailed working of the comment system and the interaction between various components, which enable us to make some design decisions before embarking on the design problem.

Design overview#

The following figure demonstrates how a comment system works. All client requests are passed through the API gateway and fan out to multiple back-end services. Upon receiving a comment for a post, the back-end server sets various attributes for the comment, appends it to the relevant post, and stores it in the database. Other requests, such as updating or deleting a comment, are handled similarly.

For brevity, we assume that our comment service offers only textual content as part of the comment. The following table describes some of the essential components involved in the design of the comment service.

Workflow#

Let's go over how all the components involved in the comment service interact with each other to perform an operation requested by a client.

The client-initiated requests are passed through the API gateway. The API gateway performs operations relevant to identity and access management—whether to allow the request for further processing or not. Upon successful verification, the user can perform more operations, such as creating, retrieving, editing, or deleting a comment.

The API gateway directs the requests to the comment service. Whenever a request for a comment is received, this service further consults with the other services, the user and the posts service, to fetch the required information relevant to a comment. For example, when a user wants to create a comment, the comment service validates the user information via user service. Similarly, the post on which the comment is made is determined via the posts service. Furthermore, the comment is created and stored with the relevant user and post information and other metadata via the comment service.

Here, the point of interest is which architectural style we need to use for communication between the three main components: the client, API gateway, and back-end services. What are the criteria for adopting a specific architectural style? We’ll answer this question in the following section.

Design considerations#

We have seen how the comment system works. We can now decide on an API architecture style for the interaction between the client, the API gateway, and the back-end services. Let’s go over the data formats and HTTP version to be adopted in the design of our API.

Architecture styles#

First, we’ll describe the interaction between the client, API gateway, and comment service with respect to different API architecture styles.

Client to API gateway#

The primary tasks relevant to comments are creating, retrieving, updating, and deleting comments. All these tasks can be performed via CRUD operations that best fit the REST API architecture style. So here, we adopt the REST style without embedding any additional complexities amid the interacting entities.

API gateway to back-end services#

An interesting part of the design is deciding the architecture style for the interaction between the API gateway and back-end servers. Let's evaluate the suitability of architectural styles for the interaction between these two entities.

• REST: This style provides a standardized way to manage and access structured resources—in our case, the user comments. Furthermore, REST provides CRUD operations and is relatively simpler than GraphQL, making it a suitable option for our service.

• GraphQL: In the comment system, we have three data sources that could be accessed by multiple client applications—for example, mobile and web applications. GraphQL is a better option for an application where a single data source is shared by multiple clients or if data is to be retrieved from multiple endpoints. Another disadvantage of GraphQL is that it is overly complicated to implement, which means we should avoid using it for a simple service like the comment API. Furthermore, the efficiency that GraphQL may offer would be negligible compared to the complexities it would introduce in a simple service like that of comments.

• gRPC: This architecture style is action oriented and is used when we aim to trigger a function or procedure in the back-end system. Also, gRPC is a suitable choice when there is intensive communication between entities and a persistent connection is required. However, in the comment service, we aim to manipulate resources that can be performed via CRUD operations, which are more aligned with the REST architecture style.

By comparing and considering different architecture styles, we conclude that REST is the most suitable API architecture style to adopt for communication between the API gateway and back-end servers. However, we should note that each style has its own pros and cons. There aren’t any strict use cases or rules about adopting one instead of the other. However, to enhance the effectiveness of communication between any two systems, we need to opt for the style that has the most advantages over the others.

Data formats#

Several data formats exist that can be adopted in our proposed API for a comment server, as given below:

• JSON: We need to exchange data related to comments between a client and a server—for example, comment IDs to be retrieved, thread IDs, and comment text. JSON suits our requirements because it is human readable and more compact than the XML and HTML data formats.

• XML: Although XML can represent more complicated data than JSON and supports object representations as well, it has several significant disadvantages that make it less ideal for our API service, including greater encoded file sizes and a lack of built-in support for parsers.

• Binary: When compared to textual representations, binary formats are quick to process and less in size, but they compromise human readability, making it difficult to troubleshoot issues and comprehend errors. This format is suitable in cases when we need to transfer large files, such as images, videos, and so on. However, for sending a number of entities and retrieving comments, adopting the binary data formats could be an expensive choice.

JSON is the suitable choice for client and API gateway communication for better readability and debugging. In fact, it’s also a good choice for communication between the API gateway and back-end services because the comment service also uses REST architecture for downstream services. Furthermore, the data exchanged using the comments service is limited. Therefore, using binary formats will offer little efficiency in comparison to the complexity it will add.

HTTP version#

We have HTTP/1.1, HTTP/2.0, and HTTP/3.0 in hand. Let's see which protocol to choose for our API.

• HTTP/1.1: The comment operations are simple CRUD, and we need a reliable connection to perform such operations; therefore, HTTP/1.1 is a suitable choice. This version is suitable when we don't want to provide a live comments service where comments are queued and batch processed frequently.

• HTTP/2.0: The main features of HTTP/2.0 are backward compatibility, multiplexing, and headers compression. HTTP/2.0 is optimal when there is an enormous number of concurrent client requests on a platform where users can post comments on live content. HTTP/2.0 could be an optimal choice because it supports multiplexing and headers compression, thereby reducing latency and bandwidth needs. However, we opted for JSON instead of binary for exchanging data between client and server; therefore, choosing HTTP/2.0 may not be an optimal choice in the comment API.

• HTTP/3.0: Since this HTTP version is faster than the previous versions, adopting this version in the API would make the system more efficient. However, this version is still in its infant version, and most organizations are still transitioning from HTTP/1.1 to HTTP/2.0. Therefore, Clients and servers should support this version to avoid incompatibility in the future, which might be a bit early in today's era.

Summary#

In this lesson, we focused on various design considerations that affect the design of our API for a comment service. We discussed various architecture styles, data formats, HTTP versions, and security mechanisms to adopt while designing the API. The following table summarizes the design decisions that have been taken and will be followed in the next lesson to devise message formats relevant to various operations on comments.